package com.tbynet.jwp.service;

import com.jfinal.aop.Inject;
import com.jfinal.kit.StrKit;
import com.jfinal.log.Log;
import com.jfinal.plugin.activerecord.Page;
import com.tbynet.jwp.framework.aop.Aop;
import com.tbynet.jwp.framework.core.JwpService;
import com.tbynet.jwp.framework.exception.BusinessException;
import com.tbynet.jwp.service.dto.request.TermRequest;
import com.tbynet.jwp.service.dto.response.TermResponse;
import com.tbynet.jwp.service.support.TermCacheManager;
import com.tbynet.jwp.service.support.TermResponseBuilder;
import com.tbynet.jwp.service.support.TermValidator;
import com.tbynet.jwp.service.task.TermBatchDeleteTask;
import com.tbynet.jwp.service.task.TermCacheCleanTask;
import com.tbynet.jwp.repository.spi._TermCommandRepository;
import com.tbynet.jwp.repository.spi._TermQueryRepository;
import com.tbynet.jwp.repository.dto.command.TermCreateCommand;
import com.tbynet.jwp.repository.dto.command.TermUpdateCommand;
import com.tbynet.jwp.repository.dto.query.TermQuery;
import com.tbynet.jwp.repository.dto.result.TermResult;

import java.math.BigInteger;
import java.util.*;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;
import java.util.stream.Collectors;

/**
 * 分类项管理器实现类 - WordPress 4.9 功能对标
 * *
 * 服务编排层，负责组合多个Service方法完成复杂业务用例，并管理事务
 * *
 * 核心功能：
 * - 分类项的CRUD操作
 * - 层级结构管理
 * - 缓存管理
 * - 批量操作
 * - 数据完整性验证
 * *
 * 设计原则：
 * - 业务导向：一个方法完成一个完整的业务用例
 * - 事务边界：在管理器层定义事务边界
 * - 无SQL：不包含任何SQL代码，只编排Service方法
 * - 异常传递：Service层异常直接抛出，不捕获转换
 *
 * @author 佰亿互联
 * @version 3.0
 * @since 2025-11-04
 */
@Aop(TermService.class)
public class _TermServiceImpl extends JwpService implements TermService {

    /** 日志记录器 */
    private final Log log = Log.getLog(this.getClass());

    // ========== 配置常量 ==========

    /** WordPress 4.9 支持的默认分类法 */
    private static final List<String> DEFAULT_TAXONOMIES = Arrays.asList(
            "category", "post_tag", "nav_menu", "link_category", "post_format"
    );

    /** 默认搜索限制数量 */
    private static final int DEFAULT_SEARCH_LIMIT = 20;

    /** 默认分析天数 */
    private static final int DEFAULT_ANALYSIS_DAYS = 30;

    /** 默认推荐数量 */
    private static final int DEFAULT_RECOMMENDATION_LIMIT = 5;

    /** 缓存超时时间（秒） */
    private static final long CACHE_TIMEOUT_SECONDS = 10;

    // ========== 依赖注入 ==========

    /** 分类项命令服务 */
    @Inject
    _TermCommandRepository termCommandRepository;

    /** 分类项查询服务 */
    @Inject
    _TermQueryRepository termQueryRepository;

    /** 缓存管理器 */
    @Inject
    TermCacheManager cacheManager;


    // ========== 核心分类项管理方法 ==========

    /**
     * 创建分类项
     *
     * @param request 创建请求参数
     * @return TermResponse.DetailInfo 新创建的分类项详情
     * @throws BusinessException 业务逻辑错误（如分类项已存在）
     */
    @Override
    public TermResponse.DetailInfo createTerm(TermRequest request) {
        validateCreateRequest(request);

        if (isTermExists(request.getName(), request.getTaxonomy())) {
            throw new BusinessException("TERM_ALREADY_EXISTS",
                    String.format("分类项已存在，name: %s, taxonomy: %s", request.getName(), request.getTaxonomy()));
        }

        final BigInteger[] newTermId = new BigInteger[1];
        final TermResult[] newTermResult = new TermResult[1];

        // 在事务内完成所有操作
        executeInTransaction(() -> {
            TermCreateCommand createCommand = buildCreateCommand(request);
            newTermId[0] = termCommandRepository.createTerm(createCommand);

            if (newTermId[0] == null) {
                throw new BusinessException("CREATE_TERM_FAILED", "创建分类项失败");
            }

            // 立即查询新创建的数据（在事务内）
            newTermResult[0] = termQueryRepository.getTermById(newTermId[0], request.getTaxonomy());
            if (newTermResult[0] == null) {
                throw new BusinessException("TERM_CREATE_QUERY_FAILED", "创建后查询分类项失败");
            }

            handleAfterTermCreate(newTermId[0], request);
            return true;
        });

        // 事务外：原子刷新缓存
        try {
            cacheManager.refreshTermCache(newTermId[0], request.getTaxonomy(),
                    () -> newTermResult[0]);
        } catch (Exception e) {
            log.warn("创建分类项后刷新缓存失败", e);
            // 即使缓存失败，也返回成功，因为数据已经持久化
        }

        // 创建后的一致性检查
        ensureCacheConsistency(newTermId[0], request.getTaxonomy());

        return buildDetailInfo(newTermResult[0], request.getTaxonomy());
    }

    /**
     * 更新分类项
     *
     * @param request 更新请求参数
     * @return TermResponse.DetailInfo 更新后的分类项详情
     * @throws BusinessException 业务逻辑错误（如循环引用）
     */
    @Override
    public TermResponse.DetailInfo updateTerm(TermRequest request) {
        validateUpdateRequest(request);

        // 在事务开始前获取旧数据
        TermResult oldTerm = getTermWithCache(request.getTermId(), request.getTaxonomy());
        if (oldTerm == null) {
            throw new BusinessException("分类项不存在").withContext("termId", request.getTermId());
        }

        // 防止循环引用
        if (request.getParentId() != null &&
                !request.getParentId().equals(BigInteger.ZERO) &&
                isCircularReference(request.getTermId(), request.getParentId(), request.getTaxonomy())) {
            throw new BusinessException("检测到循环引用：不能将父级设置为自己的后代").withContext("termId", request.getTermId()).withContext("parentId", request.getParentId());
        }

        final TermResult[] updatedTerm = new TermResult[1];

        // 在事务内完成更新和查询
        executeInTransaction(() -> {
            TermUpdateCommand updateCommand = buildUpdateCommand(request);
            boolean updateSuccess = termCommandRepository.updateTerm(updateCommand);

            if (!updateSuccess) {
                throw new BusinessException("更新分类项失败").withContext("termId", request.getTermId());
            }

            // 立即查询更新后的数据（在事务内）
            updatedTerm[0] = termQueryRepository.getTermById(request.getTermId(), request.getTaxonomy());
            return true;
        });

        // 事务外：原子刷新缓存
        try {
            cacheManager.refreshTermCache(request.getTermId(), request.getTaxonomy(),
                    () -> updatedTerm[0]);

            // 如果父级发生变化，清理相关缓存
            if (updatedTerm[0] != null &&
                    !Objects.equals(oldTerm.getParentId(), updatedTerm[0].getParentId())) {

                // 清理旧父级缓存
                if (oldTerm.getParentId() != null && !oldTerm.getParentId().equals(BigInteger.ZERO)) {
                    cacheManager.removeHierarchyCache(request.getTaxonomy(), oldTerm.getParentId());
                }

                // 清理新父级缓存
                if (updatedTerm[0].getParentId() != null && !updatedTerm[0].getParentId().equals(BigInteger.ZERO)) {
                    cacheManager.removeHierarchyCache(request.getTaxonomy(), updatedTerm[0].getParentId());
                }
            }

        } catch (Exception e) {
            log.warn("更新分类项后刷新缓存失败", e);
        }

        // 更新后的一致性检查
        ensureCacheConsistency(request.getTermId(), request.getTaxonomy());

        return buildDetailInfo(updatedTerm[0], request.getTaxonomy());
    }

    /**
     * 删除分类项
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return Boolean 删除是否成功
     * @throws BusinessException 业务逻辑错误（如分类项被使用）
     */
    @Override
    public Boolean deleteTerm(BigInteger termId, String taxonomy) {
        TermValidator.validateUpdateParams(termId, taxonomy);

        final TermResult[] deletedTerm = new TermResult[1];
        final Boolean[] deleteResult = new Boolean[1];

        // 在事务内完成所有操作
        executeInTransaction(() -> {
            // 获取要删除的分类项信息（在事务内）
            deletedTerm[0] = termQueryRepository.getTermById(termId, taxonomy);
            if (deletedTerm[0] == null) {
                throw new BusinessException("分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
            }

            // 检查业务约束
            if (Optional.of(deletedTerm[0]).map(TermResult::getCount).orElse(0) > 0) {
                throw new BusinessException("分类项有关联文章，无法删除").withContext("termId", termId);
            }

            if (hasChildTerms(termId, taxonomy)) {
                throw new BusinessException("分类项有子分类项，无法删除").withContext("termId", termId);
            }

            // 执行删除
            deleteResult[0] = termCommandRepository.deleteTerm(termId, taxonomy);
            return deleteResult[0];
        });

        // 事务外：只有在事务成功提交后才清理缓存（删除操作不需要刷新，直接清理）
        if (Boolean.TRUE.equals(deleteResult[0]) && deletedTerm[0] != null) {
            try {
                // 使用删除前的信息进行缓存清理
                handleAfterTermDelete(termId, taxonomy, deletedTerm[0]);
            } catch (Exception e) {
                log.warn("删除分类项后清理缓存失败", e);
                // 这里不抛出异常，因为数据删除已经成功
            }

            // 删除后的一致性检查
            ensureCacheConsistencyAfterDelete(termId, taxonomy);
        }

        return Boolean.TRUE.equals(deleteResult[0]);
    }

    /**
     * 批量删除分类项
     *
     * @param request 批量删除请求参数
     * @return TermResponse.BatchOperationResult 批量操作结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.BatchOperationResult batchDeleteTerms(TermRequest request) {
        // 参数验证
        validateBatchRequest(request);

        final List<BigInteger> successIds = new ArrayList<>();
        final List<BigInteger> failedIds = new ArrayList<>();
        final List<TermResult> preFetchedTerms = new ArrayList<>();

        // 阶段1：事务内执行删除操作
        executeInTransaction(() -> {
            // 预先获取分类项信息（在事务内）
            preFetchedTerms.addAll(preFetchTermInfos(request.getTermIds(), request.getTaxonomy()));

            // 执行删除操作
            for (BigInteger termId : request.getTermIds()) {
                try {
                    if (deleteSingleTermInTransaction(termId, request.getTaxonomy())) {
                        successIds.add(termId);
                    } else {
                        failedIds.add(termId);
                    }
                } catch (Exception e) {
                    log.error("删除分类项异常，termId: %s", termId, e);
                    failedIds.add(termId);
                }
            }
            return true;
        });

        // 阶段2：事务提交后异步执行缓存清理
        if (!successIds.isEmpty()) {
            executeCacheCleanupTask(successIds, request.getTaxonomy(), preFetchedTerms);
        }

        // 构建结果
        return TermResponseBuilder.buildBatchResult(
                request.getTermIds().size(), successIds.size(), successIds, failedIds);
    }


    /**
     * 获取分类项详情
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return TermResponse.DetailInfo 分类项详情信息
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.DetailInfo getTermDetail(BigInteger termId, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, taxonomy);

        // 获取带缓存的分类项详情
        TermResponse.DetailInfo detailInfo = getTermDetailWithCache(termId, taxonomy);
        if (detailInfo == null) {
            throw new BusinessException("分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
        }

        return detailInfo;
    }

    /**
     * 获取分类项列表
     *
     * @param request 查询请求参数
     * @return TermResponse.ListResult 分类项列表结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.ListResult listTerms(TermRequest request) {
        // 构建查询条件
        TermQuery query = buildTermQuery(request);

        // 执行分页查询
        Page<TermResult> termPage = termQueryRepository.paginateTerms(query);
        if (termPage == null) {
            return TermResponseBuilder.buildEmptyListResult();
        }

        // 转换结果
        List<TermResponse.BasicInfo> basicInfos = Optional.ofNullable(termPage.getList())
                .orElse(Collections.emptyList())
                .stream()
                .map(TermResponseBuilder::convertToBasicInfo)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        // 构建响应
        TermResponse.ListResult result = TermResponseBuilder.buildListResult(
                basicInfos,
                (int) termPage.getTotalRow(),
                termPage.getTotalPage(),
                termPage.getPageNumber(),
                termPage.getPageSize()
        );

        // 设置附加信息
        if (request.getTaxonomies() != null && request.getTaxonomies().size() == 1) {
            result.setTaxonomy(request.getTaxonomies().get(0));
        }

        return result;
    }

    // ========== WordPress 4.9 层级和关系方法 ==========

    /**
     * 获取分类项层级结构
     *
     * @param taxonomy 分类法类型
     * @param parentId 父级ID（可选）
     * @return TermResponse.HierarchyResult 层级结构结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.HierarchyResult getTermHierarchy(String taxonomy, BigInteger parentId) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        // 构建缓存键
        String cacheKey = cacheManager.buildHierarchyCacheKey(taxonomy, parentId);
        log.debug("Get term hierarchy from cache: %s", cacheKey);

        // 从缓存获取或加载数据
        return cacheManager.getTaxonomyCache(cacheKey, () -> {
            List<TermResult> terms = termQueryRepository.getTermHierarchy(taxonomy, parentId);
            List<TermResponse.HierarchyResult.HierarchyTerm> hierarchyTerms =
                    buildHierarchyTerms(terms, taxonomy, 0);

            TermResponse.HierarchyResult result = new TermResponse.HierarchyResult();
            result.setHierarchyTerms(hierarchyTerms);
            result.setTotal((long) hierarchyTerms.size());
            result.setTaxonomy(taxonomy);
            result.setParentId(parentId);

            return result;
        });
    }

    /**
     * 根据文章ID获取关联的分类项
     *
     * @param postId 文章ID
     * @param taxonomy 分类法类型
     * @return TermResponse.ListResult 关联的分类项列表
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.ListResult getTermsByPostId(BigInteger postId, String taxonomy) {
        // 参数验证
        if (postId == null || StrKit.isBlank(taxonomy)) {
            throw new BusinessException("文章ID和分类法类型不能为空").withContext("postId", postId).withContext("taxonomy", taxonomy);
        }

        // 查询文章关联的分类项
        List<TermResult> termResults = termQueryRepository.getTermsByPostId(postId, taxonomy);
        List<TermResponse.BasicInfo> basicInfos = Optional.ofNullable(termResults)
                .orElse(Collections.emptyList())
                .stream()
                .map(TermResponseBuilder::convertToBasicInfo)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        // 构建响应
        TermResponse.ListResult result = TermResponseBuilder.buildSimpleListResult(basicInfos);
        result.setPostId(postId);
        result.setTaxonomy(taxonomy);

        return result;
    }

    // ========== WordPress 4.9 统计和元数据方法 ==========

    /**
     * 获取分类项统计信息
     *
     * @return TermResponse.Statistics 统计信息
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.Statistics getTermStatistics() {
        TermResponse.Statistics statistics = new TermResponse.Statistics();

        // 分类法统计
        Map<String, Long> taxonomyCounts = termQueryRepository.countTermsByTaxonomies(DEFAULT_TAXONOMIES);
        statistics.setTaxonomyCounts(taxonomyCounts != null ? taxonomyCounts : new HashMap<>());

        // 总计数
        Long totalTerms = taxonomyCounts != null ?
                taxonomyCounts.values().stream().mapToLong(Long::longValue).sum() : 0L;
        statistics.setTotalTerms(totalTerms);

        // 最近创建的分类项
        statistics.setRecentTerms(getRecentTerms(DEFAULT_TAXONOMIES, 5));

        // 热门分类项
        statistics.setPopularTerms(getPopularTerms(DEFAULT_TAXONOMIES, 10));

        // 空分类项统计
        Map<String, Long> emptyCounts = new HashMap<>();
        for (String taxonomy : DEFAULT_TAXONOMIES) {
            try {
                Long emptyCount = termQueryRepository.countEmptyTerms(taxonomy);
                emptyCounts.put(taxonomy, emptyCount != null ? emptyCount : 0L);
            } catch (Exception e) {
                log.warn("获取空分类项统计失败，taxonomy: %s", taxonomy, e);
                emptyCounts.put(taxonomy, 0L);
            }
        }
        statistics.setEmptyCounts(emptyCounts);

        return statistics;
    }

    /**
     * 设置分类项元数据
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键
     * @param metaValue 元数据值
     * @return Boolean 设置是否成功
     * @throws BusinessException 数据访问异常
     */
    @Override
    public Boolean setTermMeta(BigInteger termId, String metaKey, Object metaValue) {
        // 参数验证
        TermValidator.validateTermId(termId);
        if (StrKit.isBlank(metaKey)) {
            throw new BusinessException("元数据键不能为空").withContext("termId", termId);
        }

        // 在事务中执行设置操作
        return executeInTransaction(() -> {
            // 执行设置元数据
            boolean success = termCommandRepository.setTermMeta(termId, metaKey, metaValue);
            if (success) {
                // 清理缓存
                cleanTermRelatedCache(termId, null);
            }
            return success;
        });
    }

    /**
     * 获取分类项元数据
     *
     * @param termId 分类项ID
     * @param metaKey 元数据键
     * @return Object 元数据值
     * @throws BusinessException 数据访问异常
     */
    @Override
    public Object getTermMeta(BigInteger termId, String metaKey) {
        // 参数验证
        TermValidator.validateTermId(termId);

        // 获取元数据
        return termQueryRepository.getTermMeta(termId, metaKey);
    }

    // ========== WordPress 4.9 高级功能方法 ==========

    /**
     * 更新分类项计数
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return Boolean 更新是否成功
     * @throws BusinessException 数据访问异常
     */
    @Override
    public Boolean updateTermCount(BigInteger termId, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, taxonomy);

        // 在事务中执行更新操作
        return executeInTransaction(() -> {
            // 存在性检查
            if (!isTermExists(termId, taxonomy)) {
                throw new BusinessException("分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
            }

            // 更新计数
            boolean success = termCommandRepository.updateTermCount(termId, taxonomy);
            if (success) {
                cleanTermRelatedCache(termId, taxonomy);
            }
            return success;
        });
    }

    /**
     * 清理未使用的分类项
     *
     * @param taxonomy 分类法类型
     * @return TermResponse.BatchOperationResult 批量操作结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.BatchOperationResult cleanupUnusedTerms(String taxonomy) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        final List<BigInteger> unusedTermIds = new ArrayList<>();
        final Integer[] cleanedCount = new Integer[1];

        // 在事务中执行清理
        executeInTransaction(() -> {
            // 查找并删除空分类项
            List<BigInteger> _unusedTermIds = termQueryRepository.findUnusedTerms(taxonomy);
            cleanedCount[0] = termCommandRepository.batchDeleteTerms(_unusedTermIds, taxonomy);

            if (cleanedCount[0] != null && cleanedCount[0] > 0) {
                // 清理相关缓存
                cacheManager.batchRemoveTermCache(_unusedTermIds, taxonomy);
            }

            unusedTermIds.clear();
            unusedTermIds.addAll(_unusedTermIds);

            return true;
        });

        // 构建结果
        return TermResponseBuilder.buildBatchResult(
                unusedTermIds.size(),
                cleanedCount[0] != null ? cleanedCount[0] : 0,
                unusedTermIds,
                new ArrayList<>()
        );
    }

    /**
     * 搜索分类项
     *
     * @param keyword 搜索关键词
     * @param taxonomy 分类法类型（可选）
     * @param limit 限制数量
     * @return TermResponse.ListResult 搜索结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.ListResult searchTerms(String keyword, String taxonomy, Integer limit) {
        // 参数验证
        TermValidator.validateSearchKeyword(keyword);

        // 设置实际限制数量
        int actualLimit = limit != null ? limit : DEFAULT_SEARCH_LIMIT;

        // 执行搜索
        List<TermResult> searchResults = termQueryRepository.searchTerms(keyword, taxonomy, actualLimit);
        List<TermResponse.BasicInfo> basicInfos = Optional.ofNullable(searchResults)
                .orElse(Collections.emptyList())
                .stream()
                .map(TermResponseBuilder::convertToBasicInfo)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        // 构建响应
        TermResponse.ListResult result = TermResponseBuilder.buildSimpleListResult(basicInfos, actualLimit);
        result.setSearchKeyword(keyword);
        result.setTaxonomy(taxonomy);

        return result;
    }

    /**
     * 合并分类项
     *
     * @param sourceTermId 源分类项ID
     * @param targetTermId 目标分类项ID
     * @param taxonomy 分类法类型
     * @return TermResponse.MergeResult 合并结果
     * @throws BusinessException 业务逻辑错误
     */
    @Override
    public TermResponse.MergeResult mergeTerms(BigInteger sourceTermId, BigInteger targetTermId, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(sourceTermId, taxonomy);
        TermValidator.validateUpdateParams(targetTermId, taxonomy);

        if (sourceTermId.equals(targetTermId)) {
            throw new BusinessException("不能合并相同的分类项").withContext("sourceTermId", sourceTermId).withContext("targetTermId", targetTermId);
        }

        // 在事务中执行合并操作
        final TermResult[] sourceTerm = new TermResult[1];
        final TermResult[] targetTerm = new TermResult[1];

        executeInTransaction(() -> {
            // 验证分类项存在
            sourceTerm[0] = getTermWithCache(sourceTermId, taxonomy);
            targetTerm[0] = getTermWithCache(targetTermId, taxonomy);

            if (sourceTerm[0] == null || targetTerm[0] == null) {
                throw new BusinessException("源分类项或目标分类项不存在").withContext("sourceTermId", sourceTermId).withContext("targetTermId", targetTermId);
            }

            // 执行合并
            boolean mergeSuccess = termCommandRepository.mergeTerms(sourceTermId, targetTermId, taxonomy);
            if (!mergeSuccess) {
                throw new BusinessException("合并分类项失败");
            }

            // 清理缓存
            cleanTermRelatedCache(sourceTermId, taxonomy);
            cleanTermRelatedCache(targetTermId, taxonomy);
            return true;
        });

        // 构建结果
        return TermResponseBuilder.buildMergeResult(
                true, sourceTermId, targetTermId,
                sourceTerm[0] != null ? sourceTerm[0].getName() : "",
                targetTerm[0] != null ? targetTerm[0].getName() : "",
                sourceTerm[0] != null ? (sourceTerm[0].getCount() != null ? sourceTerm[0].getCount() : 0) : 0
        );
    }

    // ========== WordPress 4.9 默认分类项管理 ==========

    /**
     * 设置默认分类项
     *
     * @param taxonomy 分类法类型
     * @param termId 分类项ID
     * @return TermResponse.OperationResult 操作结果
     * @throws BusinessException 业务逻辑错误
     */
    @Override
    public TermResponse.OperationResult setDefaultTerm(String taxonomy, BigInteger termId) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);
        TermValidator.validateTermId(termId);

        // 在事务中执行设置操作
        executeInTransaction(() -> {
            // 验证分类项存在
            TermResult term = getTermWithCache(termId, taxonomy);
            if (term == null) {
                throw new BusinessException("分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
            }

            // 设置默认分类项
            boolean setSuccess = termCommandRepository.setDefaultTerm(taxonomy, termId);
            if (!setSuccess) {
                throw new BusinessException("设置默认分类项失败");
            }

            // 清理缓存
            cacheManager.removeTaxonomyCache("default:" + taxonomy);
            return true;
        });

        return TermResponseBuilder.buildOperationResult(true, "设置默认分类项成功", termId);
    }

    /**
     * 获取默认分类项
     *
     * @param taxonomy 分类法类型
     * @return TermResponse.DetailInfo 默认分类项详情
     * @throws BusinessException 数据访问异常
     */
    @Override
    public TermResponse.DetailInfo getDefaultTerm(String taxonomy) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        // 获取默认分类项（带缓存）
        String cacheKey = "default:" + taxonomy;
        BigInteger defaultTermId = cacheManager.getTaxonomyCache(cacheKey, () -> {
            TermResult defaultTerm = termQueryRepository.getDefaultTerm(taxonomy);
            if (defaultTerm == null) {
                throw new BusinessException("默认分类项不存在").withContext("taxonomy", taxonomy);
            }
            return defaultTerm.getTermId();
        });

        return getTermDetailWithCache(defaultTermId, taxonomy);
    }

    // ========== WordPress 4.9 转换和复制方法 ==========

    /**
     * 转换分类项
     *
     * @param termId 分类项ID
     * @param sourceTaxonomy 源分类法类型
     * @param targetTaxonomy 目标分类法类型
     * @return TermResponse.TransformResult 转换结果
     * @throws BusinessException 业务逻辑错误
     */
    @Override
    public TermResponse.TransformResult transformTerm(BigInteger termId, String sourceTaxonomy, String targetTaxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, sourceTaxonomy);
        TermValidator.validateTaxonomy(targetTaxonomy);

        if (sourceTaxonomy.equals(targetTaxonomy)) {
            throw new BusinessException("源分类法和目标分类法相同").withContext("sourceTaxonomy", sourceTaxonomy).withContext("targetTaxonomy", targetTaxonomy);
        }

        // 在事务中执行转换操作
        final TermResult[] sourceTerm = new TermResult[1];
        final BigInteger[] newTermId = new BigInteger[1];

        executeInTransaction(() -> {
            // 验证源分类项存在
            sourceTerm[0] = getTermWithCache(termId, sourceTaxonomy);
            if (sourceTerm[0] == null) {
                throw new BusinessException("源分类项不存在").withContext("termId", termId).withContext("taxonomy", sourceTaxonomy);
            }

            // 检查目标分类法是否存在同名分类项
            if (isTermExists(sourceTerm[0].getName(), targetTaxonomy)) {
                throw new BusinessException("目标分类法中已存在同名分类项");
            }

            // 执行转换
            newTermId[0] = termCommandRepository.transformTerm(termId, sourceTaxonomy, targetTaxonomy);
            if (newTermId[0] == null) {
                throw new BusinessException("转换分类项失败");
            }

            // 清理缓存
            cleanTermRelatedCache(termId, sourceTaxonomy);
            cleanTermRelatedCache(newTermId[0], targetTaxonomy);
            return true;
        });

        // 构建结果
        return TermResponseBuilder.createSuccessTransformResult(termId, newTermId[0], sourceTaxonomy, targetTaxonomy, sourceTerm[0]);
    }

    /**
     * 复制分类项
     *
     * @param termId 源分类项ID
     * @param newName 新分类项名称
     * @param taxonomy 分类法类型
     * @return TermResponse.DetailInfo 新分类项详情
     * @throws BusinessException 业务逻辑错误
     */
    @Override
    public TermResponse.DetailInfo duplicateTerm(BigInteger termId, String newName, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, taxonomy);
        TermValidator.validateTermName(newName);

        // 检查新名称是否已存在
        if (isTermExists(newName, taxonomy)) {
            throw new BusinessException("目标名称已存在").withContext("newName", newName).withContext("taxonomy", taxonomy);
        }

        // 在事务中执行复制操作
        final BigInteger[] newTermId = new BigInteger[1];

        executeInTransaction(() -> {
            // 验证源分类项存在
            TermResult sourceTerm = getTermWithCache(termId, taxonomy);
            if (sourceTerm == null) {
                throw new BusinessException("源分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
            }

            // 执行复制
            newTermId[0] = termCommandRepository.duplicateTerm(termId, newName, taxonomy);
            if (newTermId[0] == null) {
                throw new BusinessException("复制分类项失败");
            }

            // 复制元数据
            termCommandRepository.copyTermMeta(termId, newTermId[0]);
            return true;
        });

        // 返回新分类项详情
        return getTermDetailWithCache(newTermId[0], taxonomy);
    }

    // ========== WordPress 4.9 分类法管理方法 ==========

    /**
     * 获取分类法详情
     *
     * @param taxonomy 分类法类型
     * @return TermResponse.TaxonomyInfo 分类法详情
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.TaxonomyInfo getTaxonomyDetail(String taxonomy) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        // 获取分类法信息（带缓存）
        String cacheKey = "taxonomy:" + taxonomy;
        return cacheManager.getTaxonomyCache(cacheKey, () -> {
            Map<String, Object> taxonomyInfo = termQueryRepository.getTaxonomyInfo(taxonomy);
            if (taxonomyInfo == null || taxonomyInfo.isEmpty()) {
                throw new BusinessException("分类法不存在").withContext("taxonomy", taxonomy);
            }

            // 转换为响应对象
            return TermResponseBuilder.convertToTaxonomyInfo(taxonomyInfo);
        });
    }

    /**
     * 获取分类项路径
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return TermResponse.PathResult 分类项路径结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.PathResult getTermPath(BigInteger termId, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, taxonomy);

        // 获取分类项路径
        List<TermResult> termPath = termQueryRepository.getTermPath(termId, taxonomy);
        if (termPath == null || termPath.isEmpty()) {
            throw new BusinessException("分类项路径不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
        }

        // 构建路径信息
        List<TermResponse.BasicInfo> pathInfo = termPath.stream()
                .map(TermResponseBuilder::convertToBasicInfo)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        String fullPath = pathInfo.stream()
                .map(TermResponse.BasicInfo::getName)
                .collect(Collectors.joining(" > "));

        // 构建响应
        TermResponse.PathResult result = new TermResponse.PathResult();
        result.setTermId(termId);
        result.setPath(pathInfo);
        result.setDepth(pathInfo.size() - 1);
        result.setFullPath(fullPath);
        result.setTaxonomy(taxonomy);
        
        return result;
    }

    /**
     * 检查分类项关系
     *
     * @param termId1 分类项1 ID
     * @param termId2 分类项2 ID
     * @param taxonomy 分类法类型
     * @return TermResponse.RelationCheckResult 关系检查结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.RelationCheckResult checkTermRelation(BigInteger termId1, BigInteger termId2, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId1, taxonomy);
        TermValidator.validateUpdateParams(termId2, taxonomy);

        if (termId1.equals(termId2)) {
            throw new BusinessException("不能检查相同分类项的关系");
        }

        // 检查祖先关系
        boolean isAncestor = termQueryRepository.isTermAncestor(termId2, termId1, taxonomy);
        boolean isDescendant = termQueryRepository.isTermAncestor(termId1, termId2, taxonomy);

        // 检查同层级
        List<TermResult> siblings1 = termQueryRepository.getSiblingTerms(termId1, taxonomy);
        boolean isSibling = siblings1 != null && siblings1.stream()
                .anyMatch(term -> term.getTermId().equals(termId2));

        // 计算关系深度
        int relationshipDepth = 0;
        if (isAncestor || isDescendant) {
            List<TermResult> path1 = termQueryRepository.getTermPath(termId1, taxonomy);
            List<TermResult> path2 = termQueryRepository.getTermPath(termId2, taxonomy);
            relationshipDepth = Math.abs(
                    (path1 != null ? path1.size() : 0) -
                            (path2 != null ? path2.size() : 0)
            );
        }

        return TermResponseBuilder.buildRelationCheckResult(
                termId1, termId2, taxonomy, isAncestor, isDescendant, isSibling, relationshipDepth);
    }



    // ========== WordPress 4.9 批量操作方法 ==========

    /**
     * 批量更新分类项
     *
     * @param request 批量更新请求参数
     * @return TermResponse.BatchOperationResult 批量操作结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.BatchOperationResult batchUpdateTerms(TermRequest request) {
        // 参数验证
        validateBatchRequest(request);

        // 在事务中执行批量更新
        final List<BigInteger> successIds = new ArrayList<>();
        final List<BigInteger> failedIds = new ArrayList<>();

        executeInTransaction(() -> {
            int successCount = 0;

            // 逐个更新分类项
            for (BigInteger termId : request.getTermIds()) {
                try {
                    // 验证分类项存在
                    if (!isTermExists(termId, request.getTaxonomy())) {
                        failedIds.add(termId);
                        continue;
                    }

                    // 构建更新命令
                    TermUpdateCommand updateCommand = new TermUpdateCommand();
                    updateCommand.setTermId(termId);
                    updateCommand.setName(request.getName());
                    updateCommand.setSlug(request.getSlug());
                    updateCommand.setTaxonomy(request.getTaxonomy());
                    updateCommand.setParentId(request.getParentId());
                    updateCommand.setDescription(request.getDescription());

                    // 执行更新
                    boolean updateSuccess = termCommandRepository.updateTerm(updateCommand);
                    if (updateSuccess) {
                        successCount++;
                        successIds.add(termId);
                        cleanTermRelatedCache(termId, request.getTaxonomy());
                    } else {
                        failedIds.add(termId);
                    }
                } catch (Exception e) {
                    log.error("更新分类项异常，termId: %s", termId, e);
                    failedIds.add(termId);
                }
            }

            if (successCount == 0) {
                throw new BusinessException("批量更新分类项全部失败");
            }

            return true;
        });

        // 构建结果
        return TermResponseBuilder.buildBatchResult(
                request.getTermIds().size(), successIds.size(), successIds, failedIds);
    }

    /**
     * 重新生成分类项别名
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return TermResponse.SlugUpdateResult 别名更新结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.SlugUpdateResult regenerateTermSlug(BigInteger termId, String taxonomy) {
        // 参数验证
        TermValidator.validateUpdateParams(termId, taxonomy);

        // 在事务中执行重新生成操作
        final TermResult[] term = new TermResult[1];
        final String[] newSlug = new String[1];

        executeInTransaction(() -> {
            // 验证分类项存在
            term[0] = getTermWithCache(termId, taxonomy);
            if (term[0] == null) {
                throw new BusinessException("分类项不存在").withContext("termId", termId).withContext("taxonomy", taxonomy);
            }

            // 重新生成别名
            newSlug[0] = termCommandRepository.regenerateTermSlug(termId, taxonomy);
            if (newSlug[0] == null) {
                throw new BusinessException("重新生成分类项别名失败");
            }

            // 清理缓存
            cleanTermRelatedCache(termId, taxonomy);
            return true;
        });

        // 构建结果
        return TermResponseBuilder.createSuccessSlugUpdateResult(
                termId, term[0].getSlug(), newSlug[0], term[0].getName());
    }

    // ========== WordPress 4.9 分析和推荐方法 ==========

    /**
     * 获取分类项使用分析
     *
     * @param taxonomy 分类法类型
     * @param days 分析天数
     * @return TermResponse.UsageAnalysisResult 使用分析结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.UsageAnalysisResult getTermUsageAnalysis(String taxonomy, Integer days) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        int actualDays = days != null ? days : DEFAULT_ANALYSIS_DAYS;

        // 获取使用统计
        Map<String, Object> usageStats = termQueryRepository.getTermUsageStatistics(taxonomy, actualDays);
        if (usageStats == null || usageStats.isEmpty()) {
            return TermResponseBuilder.createEmptyUsageAnalysisResult(taxonomy);
        }

        // 转换为响应对象
        return TermResponseBuilder.convertToUsageAnalysisResult(taxonomy, actualDays, usageStats);
    }

    /**
     * 清理分类项缓存
     *
     * @param termIds 分类项ID列表
     * @param taxonomy 分类法类型
     * @return TermResponse.CacheCleanResult 缓存清理结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.CacheCleanResult cleanTermCache(List<BigInteger> termIds, String taxonomy) {
        // 参数验证
        if (termIds == null || termIds.isEmpty()) {
            throw new BusinessException("清理分类项缓存参数错误").withContext("termIds", termIds);
        }

        // 使用异步任务清理缓存
        TermCacheCleanTask cleanTask = new TermCacheCleanTask(termIds, taxonomy, cacheManager);
        CompletableFuture<TermResponse.CacheCleanResult> future =
                executeAsync(cleanTask::call, "清理分类项缓存");

        try {
            // 设置超时控制
            return future.get(CACHE_TIMEOUT_SECONDS, TimeUnit.SECONDS);
        } catch (Exception e) {
            throw new BusinessException("清理分类项缓存");
        }
    }

    /**
     * 验证分类项数据完整性
     *
     * @param taxonomy 分类法类型
     * @return TermResponse.IntegrityCheckResult 完整性检查结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.IntegrityCheckResult validateTermIntegrity(String taxonomy) {
        // 参数验证
        TermValidator.validateTaxonomy(taxonomy);

        // 数据完整性检查
        List<String> issues = new ArrayList<>();
        int orphanedTerms = 0;
        int inconsistentCounts = 0;

        // 检查孤儿分类项
        List<TermResult> allTerms = termQueryRepository.listTerms(new TermQuery());
        if (allTerms != null) {
            for (TermResult term : allTerms) {
                if (term.getParentId() != null && !term.getParentId().equals(BigInteger.ZERO)) {
                    TermResult parent = termQueryRepository.getTermById(term.getParentId(), taxonomy);
                    if (parent == null) {
                        orphanedTerms++;
                        issues.add("分类项 '" + term.getName() + "' 的父级不存在");
                    }
                }
            }
        }

        // 检查计数一致性
        try {
            termCommandRepository.resetTermCounts(taxonomy);
        } catch (Exception e) {
            log.warn("重置分类项计数失败", e);
            inconsistentCounts++;
            issues.add("分类项计数重置失败");
        }

        return TermResponseBuilder.buildIntegrityCheckResult(taxonomy, issues, orphanedTerms, inconsistentCounts);
    }



    /**
     * 获取分类项推荐
     *
     * @param postId 文章ID
     * @param taxonomy 分类法类型
     * @param limit 推荐数量
     * @return TermResponse.RecommendationResult 推荐结果
     * @throws BusinessException 异常
     */
    @Override
    public TermResponse.RecommendationResult getTermRecommendations(BigInteger postId, String taxonomy, Integer limit) {
        // 参数验证
        if (postId == null || StrKit.isBlank(taxonomy)) {
            throw new BusinessException("文章ID和分类法类型不能为空").withContext("postId", postId).withContext("taxonomy", taxonomy);
        }

        int actualLimit = limit != null ? limit : DEFAULT_RECOMMENDATION_LIMIT;

        // 推荐算法（简化实现）
        List<TermResult> popularTerms = termQueryRepository.getPopularTerms(taxonomy, actualLimit * 2);
        List<TermResponse.BasicInfo> recommendedTerms = Optional.ofNullable(popularTerms)
                .orElse(Collections.emptyList())
                .stream()
                .limit(actualLimit)
                .map(TermResponseBuilder::convertToBasicInfo)
                .filter(Objects::nonNull)
                .collect(Collectors.toList());

        // 生成置信度分数
        Map<String, Double> confidenceScores = new HashMap<>();
        Random random = new Random();
        for (TermResponse.BasicInfo term : recommendedTerms) {
            confidenceScores.put(term.getName(), 0.7 + random.nextDouble() * 0.3);
        }

        return TermResponseBuilder.buildRecommendationResult(postId, taxonomy, recommendedTerms, confidenceScores);
    }


    // ========== 私有工具方法 ==========

    /**
     * 验证创建请求参数
     *
     * @param request 创建请求
     * @throws BusinessException 当参数无效时抛出
     */
    private void validateCreateRequest(TermRequest request) {
        TermValidator.validateRequest(request);
        TermValidator.validateCreateParams(request.getName(), request.getTaxonomy());
        TermValidator.validateSlug(request.getSlug());
    }

    /**
     * 验证更新请求参数
     *
     * @param request 更新请求
     * @throws BusinessException 当参数无效时抛出
     */
    private void validateUpdateRequest(TermRequest request) {
        TermValidator.validateRequest(request);
        TermValidator.validateUpdateParams(request.getTermId(), request.getTaxonomy());

        if (request.getName() != null) {
            TermValidator.validateTermName(request.getName());
        }
    }

    /**
     * 验证批量请求参数
     *
     * @param request 批量请求
     * @throws BusinessException 当参数无效时抛出
     */
    private void validateBatchRequest(TermRequest request) {
        if (request == null || request.getTermIds() == null || request.getTermIds().isEmpty() ||
                StrKit.isBlank(request.getTaxonomy())) {
            throw new BusinessException("批量操作参数错误").withContext("request", request);
        }
    }

    /**
     * 检查分类项是否存在
     *
     * @param identifier 分类项标识（名称或ID）
     * @param taxonomy 分类法类型
     * @return 是否存在
     */
    private boolean isTermExists(Object identifier, String taxonomy) {
        try {
            if (identifier instanceof String) {
                return termQueryRepository.termExists((String) identifier, taxonomy) != null;
            } else if (identifier instanceof BigInteger) {
                return termQueryRepository.termExists((BigInteger) identifier, taxonomy) != null;
            }
            return false;
        } catch (Exception e) {
            log.warn("检查分类项存在性失败", e);
            return false;
        }
    }

    /**
     * 检查循环引用（修复版）
     * 正确逻辑：检查要设置的 parentId 是否在当前分类项 termId 的祖先链中
     * 如果 parentId 是 termId 的祖先，设置 parentId 会导致循环引用
     *
     * @param termId 当前要设置父级的分类项ID
     * @param parentId 要设置的父级分类项ID
     * @param taxonomy 分类法类型
     * @return 是否存在循环引用
     */
    private boolean isCircularReference(BigInteger termId, BigInteger parentId, String taxonomy) {
        // 基础参数检查
        if (termId == null || parentId == null) {
            log.warn("循环引用检查参数为空: termId=%s, parentId=%s", termId, parentId);
            return false;
        }

        // 直接循环：不能设置自己为父级
        if (termId.equals(parentId)) {
            log.warn("检测到直接循环引用: 不能设置自己为父级, termId=%s", termId);
            return true;
        }

        // 如果 parentId 是根节点，不会形成循环
        if (parentId.equals(BigInteger.ZERO)) {
            return false;
        }

        try {
            // 正确逻辑：检查 parentId 是否在 termId 的祖先链中
            // 即检查 termId 是否是 parentId 的后代
            List<TermResult> termAncestors = getTermAncestors(termId, taxonomy);
            boolean isCircular = termAncestors.stream()
                    .anyMatch(ancestor -> parentId.equals(ancestor.getTermId()));

            if (isCircular) {
                log.warn("检测到循环引用: parentId=%s 是 termId=%s 的祖先，形成循环", parentId, termId);
            }

            return isCircular;

        } catch (Exception e) {
            log.error("检查循环引用失败, termId=%s, parentId=%s", termId, parentId, e);
            return true; // 出错时保守返回true，防止数据不一致
        }
    }

    /**
     * 获取分类项的所有祖先（从父级到根）- 优化版本
     * 添加深度限制和循环检测，防止无限递归
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 祖先列表（从直接父级到根）
     */
    private List<TermResult> getTermAncestors(BigInteger termId, String taxonomy) {
        List<TermResult> ancestors = new ArrayList<>();
        Set<BigInteger> visited = new HashSet<>(); // 防循环检测
        BigInteger currentId = termId;
        int maxDepth = 100; // 合理深度限制
        int currentDepth = 0;

        while (currentId != null &&
                !currentId.equals(BigInteger.ZERO) &&
                currentDepth < maxDepth) {

            currentDepth++;

            // 防循环检测
            if (visited.contains(currentId)) {
                log.error("检测到祖先链循环, termId=%s, currentId=%s, visited=%s",
                        termId, currentId, visited);
                break;
            }
            visited.add(currentId);

            // 获取当前分类项
            TermResult currentTerm = termQueryRepository.getTermById(currentId, taxonomy);
            if (currentTerm == null) {
                log.debug("获取分类项失败，可能已被删除, termId=%s", currentId);
                break;
            }

            // 获取父级ID
            BigInteger parentId = currentTerm.getParentId();
            if (parentId == null || parentId.equals(BigInteger.ZERO)) {
                break; // 到达根节点
            }

            // 获取父级分类项
            TermResult parentTerm = termQueryRepository.getTermById(parentId, taxonomy);
            if (parentTerm != null) {
                ancestors.add(parentTerm);
                currentId = parentId;
            } else {
                log.warn("父级分类项不存在, parentId=%s", parentId);
                break;
            }
        }

        // 深度超限警告
        if (currentDepth >= maxDepth) {
            log.error("获取祖先链达到最大深度限制, termId=%s, maxDepth=%s", termId, maxDepth);
        }

        return ancestors;
    }

    /**
     * 检查是否有子分类项
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 是否有子分类项
     */
    private boolean hasChildTerms(BigInteger termId, String taxonomy) {
        try {
            List<TermResult> childTerms = termQueryRepository.getTermHierarchy(taxonomy, termId);
            return childTerms != null && !childTerms.isEmpty();
        } catch (Exception e) {
            log.warn("检查子分类项失败", e);
            return true; // 出错时保守返回true，避免误删
        }
    }

    /**
     * 获取分类项（带缓存）
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项结果
     */
    private TermResult getTermWithCache(BigInteger termId, String taxonomy) {
        return cacheManager.getTermWithCache(termId, taxonomy,
                () -> termQueryRepository.getTermById(termId, taxonomy));
    }

    /**
     * 获取分类项详情（带缓存）
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @return 分类项详情
     */
    private TermResponse.DetailInfo getTermDetailWithCache(BigInteger termId, String taxonomy) {
        TermResult termResult = getTermWithCache(termId, taxonomy);
        return termResult != null ? buildDetailInfo(termResult, taxonomy) : null;
    }

    /**
     * 清理分类项相关缓存
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     */
    private void cleanTermRelatedCache(BigInteger termId, String taxonomy) {
        cleanTermRelatedCache(termId, taxonomy, null);
    }

    /**
     * 清理分类项相关缓存
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @param termInfo 分类项信息（可选，如果为null则会查询）
     */
    private void cleanTermRelatedCache(BigInteger termId, String taxonomy, TermResult termInfo) {
        try {
            // 清理分类项本身缓存
            cacheManager.removeTermCache(termId, taxonomy);

            // 获取分类项信息（如果未提供则查询）
            TermResult term = termInfo;
            if (term == null) {
                try {
                    term = getTermWithCache(termId, taxonomy);
                } catch (Exception e) {
                    log.debug("获取分类项信息失败，可能已被删除，termId: %s, taxonomy: %s", termId, taxonomy);
                    // 如果分类项已被删除，我们仍然可以清理已知的缓存
                    term = null;
                }
            }

            // 精确清理相关缓存
            if (term != null) {
                // 清理父级层级缓存
                if (term.getParentId() != null && !term.getParentId().equals(BigInteger.ZERO)) {
                    cacheManager.removeHierarchyCache(taxonomy, term.getParentId());
                }

                // 清理以当前分类项为父级的层级缓存
                cacheManager.removeHierarchyCache(taxonomy, termId);
            }

            // 总是清理根层级缓存（确保数据一致性）
            cacheManager.removeHierarchyCache(taxonomy, null);

            // 清理分类法统计缓存
            cacheManager.removeTaxonomyCache("statistics:" + taxonomy);

            // 清理关联文章的缓存（使用删除前获取的信息）
            if (term != null) {
                List<BigInteger> postIds = termQueryRepository.getObjectsInTerm(termId, taxonomy);
                if (postIds != null && !postIds.isEmpty()) {
                    // TODO: 批量清理文章缓存
                    log.debug("需要清理关联文章缓存，文章数量: %s", postIds.size());
                }
            }

        } catch (Exception e) {
            log.warn("清理分类项相关缓存失败，termId: %s, taxonomy: %s", termId, taxonomy, e);
            // 这里不抛出异常，避免影响主业务流程
        }
    }

    /**
     * 构建创建命令
     *
     * @param request 创建请求
     * @return 创建命令
     */
    private TermCreateCommand buildCreateCommand(TermRequest request) {
        TermCreateCommand command = new TermCreateCommand();
        command.setName(request.getName());
        command.setSlug(request.getSlug());
        command.setTaxonomy(request.getTaxonomy());
        command.setParentId(request.getParentId());
        command.setDescription(request.getDescription());
        command.setUserId(request.getUserId());
        return command;
    }

    /**
     * 构建更新命令
     *
     * @param request 更新请求
     * @return 更新命令
     */
    private TermUpdateCommand buildUpdateCommand(TermRequest request) {
        TermUpdateCommand command = new TermUpdateCommand();
        command.setTermId(request.getTermId());
        command.setName(request.getName());
        command.setSlug(request.getSlug());
        command.setTaxonomy(request.getTaxonomy());
        command.setParentId(request.getParentId());
        command.setDescription(request.getDescription());
        command.setUserId(request.getUserId());
        return command;
    }

    /**
     * 构建查询条件
     *
     * @param request 查询请求
     * @return 查询条件
     */
    private TermQuery buildTermQuery(TermRequest request) {
        TermQuery query = new TermQuery();
        query.setTaxonomies(request.getTaxonomies());
        query.setTermIds(request.getTermIds());
        query.setParentId(request.getParentId());
        query.setHideEmpty(request.getHideEmpty());
        query.setSearch(request.getSearch());
        query.setOrderBy(request.getOrderBy());
        query.setOrder(request.getOrder());
        query.setPageSize(request.getPageSize());
        query.setPageNumber(request.getPageNumber());
        return query;
    }

    /**
     * 构建分类项详情信息
     *
     * @param termResult 分类项结果
     * @param taxonomy 分类法类型
     * @return 分类项详情
     */
    private TermResponse.DetailInfo buildDetailInfo(TermResult termResult, String taxonomy) {
        if (termResult == null) {
            return null;
        }

        TermResponse.DetailInfo detailInfo = new TermResponse.DetailInfo();
        detailInfo.setTermId(termResult.getTermId());
        detailInfo.setName(termResult.getName());
        detailInfo.setSlug(termResult.getSlug());
        detailInfo.setTaxonomy(termResult.getTaxonomy());
        detailInfo.setTaxonomyId(termResult.getTaxonomyId());
        detailInfo.setDescription(termResult.getDescription());
        detailInfo.setParentId(termResult.getParentId());
        detailInfo.setCount(termResult.getCount());
        detailInfo.setTermGroup(termResult.getTermGroup());
        detailInfo.setCreateTime(termResult.getCreateTime());
        detailInfo.setUpdateTime(termResult.getUpdateTime());

        // 安全的元数据获取
        try {
            Object metaData = termQueryRepository.getTermMeta(termResult.getTermId(), null);
            if (metaData instanceof Map) {
                @SuppressWarnings("unchecked")
                Map<String, Object> metaDataMap = (Map<String, Object>) metaData;
                detailInfo.setMetaData(metaDataMap);
            }
        } catch (Exception e) {
            log.warn("获取分类项元数据失败，termId: %s", termResult.getTermId(), e);
        }

        // 安全的父级名称获取
        if (termResult.getParentId() != null &&
                termResult.getParentId().compareTo(BigInteger.ZERO) > 0) {
            try {
                TermResult parentTerm = getTermWithCache(termResult.getParentId(), taxonomy);
                if (parentTerm != null) {
                    detailInfo.setParentName(parentTerm.getName());
                }
            } catch (Exception e) {
                log.warn("获取父级分类项名称失败，parentId: %s", termResult.getParentId(), e);
            }
        }

        return detailInfo;
    }

    /**
     * 构建层级分类项
     *
     * @param terms 分类项列表
     * @param taxonomy 分类法类型
     * @param depth 当前深度
     * @return 层级分类项列表
     */
    private List<TermResponse.HierarchyResult.HierarchyTerm> buildHierarchyTerms(
            List<TermResult> terms, String taxonomy, int depth) {

        if (terms == null) {
            return new ArrayList<>();
        }

        return terms.stream()
                .map(term -> {
                    TermResponse.HierarchyResult.HierarchyTerm hierarchyTerm =
                            new TermResponse.HierarchyResult.HierarchyTerm();
                    hierarchyTerm.setTermId(term.getTermId());
                    hierarchyTerm.setName(term.getName());
                    hierarchyTerm.setSlug(term.getSlug());
                    hierarchyTerm.setTaxonomy(term.getTaxonomy());
                    hierarchyTerm.setCount(term.getCount());
                    hierarchyTerm.setDepth(depth);

                    // 递归获取子分类项
                    try {
                        List<TermResult> childTerms = termQueryRepository.getTermHierarchy(taxonomy, term.getTermId());
                        if (childTerms != null && !childTerms.isEmpty()) {
                            hierarchyTerm.setChildren(buildHierarchyTerms(childTerms, taxonomy, depth + 1));
                        } else {
                            hierarchyTerm.setChildren(new ArrayList<>());
                        }
                    } catch (Exception e) {
                        log.warn("获取子分类项失败，termId: %s", term.getTermId(), e);
                        hierarchyTerm.setChildren(new ArrayList<>());
                    }

                    return hierarchyTerm;
                })
                .collect(Collectors.toList());
    }

    /**
     * 分类项创建后处理
     *
     * @param termId 分类项ID
     * @param request 创建请求
     */
    private void handleAfterTermCreate(BigInteger termId, TermRequest request) {
        try {
            // 设置默认元数据
            if (StrKit.notBlank(request.getDescription())) {
                termCommandRepository.setTermMeta(termId, "description", request.getDescription());
            }

            // 清理相关缓存
            cleanTermRelatedCache(termId, request.getTaxonomy());
        } catch (Exception e) {
            log.warn("分类项创建后处理失败", e);
        }
    }

    /**
     * 分类项删除后处理
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     * @param deletedTerm 已删除的分类项信息（删除前获取）
     */
    private void handleAfterTermDelete(BigInteger termId, String taxonomy, TermResult deletedTerm) {
        try {
            // 使用删除前的分类项信息进行缓存清理，避免查询已删除的数据
            cleanTermRelatedCache(termId, taxonomy, deletedTerm);

            // 清理层级缓存
            cacheManager.removeHierarchyCache(taxonomy, null);

            log.debug("分类项删除后处理完成，termId: %s, taxonomy: %s", termId, taxonomy);
        } catch (Exception e) {
            log.warn("分类项删除后处理失败，termId: %s, taxonomy: %s", termId, taxonomy, e);
            // 这里不抛出异常，避免影响主业务流程
        }
    }

    /**
     * 获取最近创建的分类项
     *
     * @param taxonomies 分类法类型列表
     * @param limit 限制数量
     * @return 最近创建的分类项列表
     */
    private List<TermResponse.BasicInfo> getRecentTerms(List<String> taxonomies, int limit) {
        try {
            TermQuery recentQuery = new TermQuery();
            recentQuery.setTaxonomies(taxonomies);
            recentQuery.setPageSize(limit);
            recentQuery.setOrderBy("term_id");
            recentQuery.setOrder("DESC");

            List<TermResult> recentTerms = termQueryRepository.listTerms(recentQuery);
            return Optional.ofNullable(recentTerms)
                    .orElse(Collections.emptyList())
                    .stream()
                    .map(TermResponseBuilder::convertToBasicInfo)
                    .filter(Objects::nonNull)
                    .collect(Collectors.toList());
        } catch (Exception e) {
            log.warn("获取最近创建的分类项失败", e);
            return new ArrayList<>();
        }
    }

    /**
     * 获取热门分类项
     *
     * @param taxonomies 分类法类型列表
     * @param limit 限制数量
     * @return 热门分类项列表
     */
    private List<TermResponse.BasicInfo> getPopularTerms(List<String> taxonomies, int limit) {
        List<TermResponse.BasicInfo> popularTerms = new ArrayList<>();
        for (String taxonomy : taxonomies) {
            try {
                List<TermResult> popular = termQueryRepository.getPopularTerms(taxonomy, limit);
                if (popular != null) {
                    popularTerms.addAll(popular.stream()
                            .map(TermResponseBuilder::convertToBasicInfo)
                            .filter(Objects::nonNull)
                            .collect(Collectors.toList()));
                }
            } catch (Exception e) {
                log.warn("获取热门分类项失败，taxonomy: %s", taxonomy, e);
            }
        }
        return popularTerms;
    }


    /**
     * 预先获取分类项信息
     */
    private List<TermResult> preFetchTermInfos(List<BigInteger> termIds, String taxonomy) {
        List<TermResult> termInfos = new ArrayList<>();
        for (BigInteger termId : termIds) {
            try {
                TermResult term = getTermWithCache(termId, taxonomy);
                if (term != null) {
                    termInfos.add(term);
                } else {
                    log.warn("无法获取分类项信息，跳过预获取: termId=%s", termId);
                }
            } catch (Exception e) {
                log.error("预获取分类项信息异常: termId=%s", termId, e);
            }
        }
        return termInfos;
    }

    /**
     * 在事务内删除单个分类项
     */
    private boolean deleteSingleTermInTransaction(BigInteger termId, String taxonomy) {
        try {
            // 获取分类项详情
            TermResult existingTerm = getTermWithCache(termId, taxonomy);
            if (existingTerm == null) {
                log.warn("分类项不存在，termId: %s", termId);
                return false;
            }

            // 检查是否被使用
            if (Optional.of(existingTerm)
                    .map(TermResult::getCount)
                    .orElse(0) > 0) {
                log.warn("分类项有关联文章，无法删除，termId: %s", termId);
                return false;
            }

            // 检查是否有子分类项
            if (hasChildTerms(termId, taxonomy)) {
                log.warn("分类项有子分类项，无法删除，termId: %s", termId);
                return false;
            }

            // 执行删除
            boolean success = termCommandRepository.deleteTerm(termId, taxonomy);
            if (success) {
                log.debug("事务内删除分类项成功: termId=%s", termId);
            }
            return success;

        } catch (Exception e) {
            log.error("事务内删除分类项失败: termId=%s", termId, e);
            return false;
        }
    }

    /**
     * 执行缓存清理任务
     */
    private void executeCacheCleanupTask(List<BigInteger> successIds, String taxonomy,
                                         List<TermResult> preFetchedTerms) {
        try {
            // 创建缓存清理任务
            TermBatchDeleteTask cacheCleanTask = new TermBatchDeleteTask(
                    successIds, taxonomy, preFetchedTerms, cacheManager);

            // 异步执行缓存清理
            CompletableFuture<TermResponse.BatchOperationResult> future =
                    executeAsync(cacheCleanTask::call, "批量删除缓存清理");

            // 可选：添加超时控制和结果处理
            future.whenComplete((result, throwable) -> {
                if (throwable != null) {
                    log.error("批量删除缓存清理任务执行失败", throwable);
                } else {
                    log.info("批量删除缓存清理完成: 成功清理 %s 个分类项",
                            result != null ? result.getSuccessCount() : 0);
                }
            });

        } catch (Exception e) {
            // 缓存清理任务创建失败不影响主流程
            log.error("创建缓存清理任务失败", e);
        }
    }

    /**
     * 增强版缓存一致性检查
     * 使用版本控制避免竞态条件，确保缓存与数据库数据一致
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     */
    private void ensureCacheConsistency(BigInteger termId, String taxonomy) {
        if (termId == null || StrKit.isBlank(taxonomy)) {
            log.warn("缓存一致性检查参数错误: termId=%s, taxonomy=%s", termId, taxonomy);
            return;
        }

        try {
            // 1. 从数据库获取最新数据
            TermResult dbTerm = termQueryRepository.getTermById(termId, taxonomy);

            // 2. 原子性刷新缓存，避免竞态条件
            if (dbTerm != null) {
                // 数据库有数据，确保缓存是最新的
                cacheManager.refreshTermCache(termId, taxonomy, () -> dbTerm);
                log.debug("缓存一致性检查: 刷新缓存成功, termId=%s", termId);
            } else {
                // 数据库没有数据，确保缓存被清理
                cacheManager.removeTermCache(termId, taxonomy);
                log.debug("缓存一致性检查: 清理缓存成功, termId=%s", termId);
            }

        } catch (Exception e) {
            log.warn("缓存一致性检查失败, termId=%s, taxonomy=%s", termId, taxonomy, e);
            // 不抛出异常，避免影响主业务流程
        }
    }

    /**
     * 删除后的特殊一致性检查
     * 专门处理删除操作后的缓存状态验证
     *
     * @param termId 分类项ID
     * @param taxonomy 分类法类型
     */
    private void ensureCacheConsistencyAfterDelete(BigInteger termId, String taxonomy) {
        if (termId == null || StrKit.isBlank(taxonomy)) {
            return;
        }

        try {
            // 1. 检查数据库是否真的没有该数据
            TermResult dbTerm = termQueryRepository.getTermById(termId, taxonomy);
            if (dbTerm != null) {
                log.error("删除后数据不一致: 数据库仍存在已删除的分类项, termId=%s", termId);
                return;
            }

            // 2. 强制清理缓存，确保没有残留
            cacheManager.removeTermCache(termId, taxonomy);

            // 3. 验证缓存是否真的被清理
            TermResult cacheTerm = getTermWithCache(termId, taxonomy);
            if (cacheTerm != null) {
                log.warn("删除后缓存清理不彻底, 进行二次清理: termId=%s", termId);
                cacheManager.completelyCleanTaxonomyCache(taxonomy);
            } else {
                log.debug("删除后缓存一致性验证通过: termId=%s", termId);
            }

        } catch (Exception e) {
            log.warn("删除后缓存一致性检查失败, termId=%s, taxonomy=%s", termId, taxonomy, e);
        }
    }

}